import logging
from typing import Optional

import mysql.connector
from mysql.connector import pooling

# --- 数据库连接池占位符 ---
# 这个全局变量将由 FastAPI 的 lifespan 管理器在应用启动时进行初始化。
cnx_pool: Optional[pooling.MySQLConnectionPool] = None


def get_db_connection():
    """
    从全局管理的连接池中获取一个连接。
    在调用此函数之前，必须在应用程序的 lifespan 中初始化连接池。

    重要提示：从此函数获得的连接必须在 'finally' 块中
    通过调用 conn.close() 来关闭，以便将其归还给连接池。
    """
    if cnx_pool is None:
        logging.critical("数据库连接池尚未初始化。")
        raise Exception("数据库连接池不可用。应用可能未正确启动。")

    try:
        conn = cnx_pool.get_connection()
        logging.debug("从连接池中获取了一个数据库连接。")
        return conn
    except mysql.connector.Error as err:
        logging.error(f"从数据库连接池获取连接失败: {err}")
        raise err
